home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / lang / perl_src.lha / fsf / perl / vms / ext / Stdio / Stdio.pm < prev    next >
Encoding:
Perl POD Document  |  1996-03-25  |  8.3 KB  |  236 lines
  1. #   VMS::Stdio - VMS extensions to Perl's stdio calls
  2. #
  3. #   Author:  Charles Bailey  bailey@genetics.upenn.edu
  4. #   Version: 2.0
  5. #   Revised: 28-Feb-1996
  6.  
  7. package VMS::Stdio;
  8.  
  9. require 5.002;
  10. use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );
  11. use Carp '&croak';
  12. use DynaLoader ();
  13. use Exporter ();
  14.  
  15. $VERSION = '2.0';
  16. @ISA = qw( Exporter DynaLoader FileHandle );
  17. @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY &O_NOWAIT
  18.               &O_RDONLY &O_RDWR  &O_TRUNC &O_WRONLY );
  19. @EXPORT_OK = qw( &flush &getname &remove &rewind &sync &tmpnam
  20.                  &vmsopen &vmssysopen &waitfh );
  21. %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY
  22.                                     &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC
  23.                                     &O_WRONLY ) ],
  24.                  FUNCTIONS => [ qw( &flush &getname &remove &rewind &sync
  25.                                      &tmpnam &vmsopen &vmssysopen &waitfh ) ] );
  26.  
  27. bootstrap VMS::Stdio $VERSION;
  28.  
  29. sub AUTOLOAD {
  30.     my($constname) = $AUTOLOAD;
  31.     $constname =~ s/.*:://;
  32.     if ($constname =~ /^O_/) {
  33.       my($val) = constant($constname);
  34.       defined $val or croak("Unknown VMS::Stdio constant $constname");
  35.       *$AUTOLOAD = sub { $val };
  36.     }
  37.     else { # We don't know about it; hand off to FileHandle
  38.       require FileHandle;
  39.       my($obj) = shift(@_);
  40.       $obj->FileHandle::$constname(@_);
  41.     }
  42.     goto &$AUTOLOAD;
  43. }
  44.  
  45. sub DESTROY { close($_[0]); }
  46.  
  47.  
  48. ################################################################################
  49. # Intercept calls to old VMS::stdio package, complain, and hand off
  50. # This will be removed in a future version of VMS::Stdio
  51.  
  52. package VMS::stdio;
  53.  
  54. sub AUTOLOAD {
  55.   my($func) = $AUTOLOAD;
  56.   $func =~ s/.*:://;
  57.   # Cheap trick: we know DynaLoader has required Carp.pm
  58.   Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");
  59.   if ($func eq 'vmsfopen') {
  60.     Carp::carp("Old function &vmsfopen is now &vmsopen");
  61.     goto &VMS::Stdio::vmsopen;
  62.   }
  63.   elsif ($func eq 'fgetname') {
  64.     Carp::carp("Old function &fgetname is now &getname");
  65.     goto &VMS::Stdio::getname;
  66.   }
  67.   else { goto &{"VMS::Stdio::$func"}; }
  68. }
  69.  
  70. package VMS::Stdio;  # in case we ever use AutoLoader
  71.  
  72. 1;
  73.  
  74. __END__
  75.  
  76. =head1 NAME
  77.  
  78. VMS::Stdio
  79.  
  80. =head1 SYNOPSIS
  81.  
  82. use VMS::Stdio qw( &flush &getname &remove &rewind &sync &tmpnam
  83.                    &vmsopen &vmssysopen &waitfh );
  84. $uniquename = tmpnam;
  85. $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
  86. $name = getname($fh);
  87. print $fh "Hello, world!\n";
  88. flush($fh);
  89. sync($fh);
  90. rewind($fh);
  91. $line = <$fh>;
  92. undef $fh;  # closes file
  93. $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
  94. sysread($fh,$data,128);
  95. waitfh($fh);
  96. close($fh);
  97. remove("another.file");
  98.  
  99. =head1 DESCRIPTION
  100.  
  101. This package gives Perl scripts access to VMS extensions to several
  102. C stdio operations not available through Perl's CORE I/O functions.
  103. The specific routines are described below.  These functions are
  104. prototyped as unary operators, with the exception of C<vmsopen>
  105. and C<vmssysopen>, which can take any number of arguments, and
  106. C<tmpnam>, which takes none.
  107.  
  108. All of the routines are available for export, though none are
  109. exported by default.  All of the constants used by C<vmssysopen>
  110. to specify access modes are exported by default.  The routines
  111. are associated with the Exporter tag FUNCTIONS, and the constants
  112. are associated with the Exporter tag CONSTANTS, so you can more
  113. easily choose what you'd like to import:
  114.  
  115.     # import constants, but not functions
  116.     use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );
  117.     # import functions, but not constants
  118.     use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS ); 
  119.     # import both
  120.     use VMS::Stdio qw( :CONSTANTS :FUNCTIONS ); 
  121.     # import neither
  122.     use VMS::Stdio ();
  123.  
  124. Of course, you can also choose to import specific functions by
  125. name, as usual.
  126.  
  127. This package C<ISA> FileHandle, so that you can call FileHandle
  128. methods on the handles returned by C<vmsopen> and C<vmssysopen>.
  129. The FileHandle package is not initialized, however, until you
  130. actually call a method that VMS::Stdio doesn't provide.  This
  131. is doen to save startup time for users who don't wish to use
  132. the FileHandle methods.
  133.  
  134. B<Note:>  In order to conform to naming conventions for Perl
  135. extensions and functions, the name of this package has been
  136. changed to VMS::Stdio as of Perl 5.002, and the names of some
  137. routines have been changed.  Calls to the old VMS::stdio routines
  138. will generate a warning, and will be routed to the equivalent
  139. VMS::Stdio function.  This compatibility interface will be
  140. removed in a future release of this extension, so please
  141. update your code to use the new routines.
  142.  
  143. =item flush
  144.  
  145. This function causes the contents of stdio buffers for the specified
  146. file handle to be flushed.  If C<undef> is used as the argument to
  147. C<flush>, all currently open file handles are flushed.  Like the CRTL
  148. fflush() routine, it does not flush any underlying RMS buffers for the
  149. file, so the data may not be flushed all the way to the disk.  C<flush>
  150. returns a true value if successful, and C<undef> if not.
  151.  
  152. =item getname
  153.  
  154. The C<getname> function returns the file specification associated
  155. with a Perl FileHandle.  If an error occurs, it returns C<undef>.
  156.  
  157. =item remove
  158.  
  159. This function deletes the file named in its argument, returning
  160. a true value if successful and C<undef> if not.  It differs from
  161. the CORE Perl function C<unlink> in that it does not try to
  162. reset file protection if the original protection does not give
  163. you delete access to the file (cf. L<perlvms>).  In other words,
  164. C<remove> is equivalent to
  165.  
  166.   unlink($file) if VMS::Filespec::candelete($file);
  167.  
  168. =item rewind
  169.  
  170. C<rewind> resets the current position of the specified file handle
  171. to the beginning of the file.  It's really just a convenience
  172. method equivalent in effect to C<seek($fh,0,0)>.  It returns a
  173. true value if successful, and C<undef> if it fails.
  174.  
  175. =item sync
  176.  
  177. This function flushes buffered data for the specified file handle
  178. from stdio and RMS buffers all the way to disk.  If successful, it
  179. returns a true value; otherwise, it returns C<undef>.
  180.  
  181. =item tmpnam
  182.  
  183. The C<tmpnam> function returns a unique string which can be used
  184. as a filename when creating temporary files.  If, for some
  185. reason, it is unable to generate a name, it returns C<undef>.
  186.  
  187. =item vmsopen
  188.  
  189. The C<vmsopen> function enables you to specify optional RMS arguments
  190. to the VMS CRTL when opening a file.  It is similar to the built-in
  191. Perl C<open> function (see L<perlfunc> for a complete description),
  192. but will only open normal files; it cannot open pipes or duplicate
  193. existing FileHandles.  Up to 8 optional arguments may follow the
  194. file name.  These arguments should be strings which specify
  195. optional file characteristics as allowed by the CRTL. (See the
  196. CRTL reference manual description of creat() and fopen() for details.)
  197. If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
  198. error occurs, it returns C<undef>.
  199.  
  200. You can use the file handle returned by C<vmsfopen> just as you
  201. would any other Perl file handle.  The class VMS::Stdio ISA
  202. FileHandle, so you can call FileHandle methods using the handle
  203. returned by C<vmsopen>.  However, C<use>ing VMS::Stdio does not
  204. automatically C<use> FileHandle; you must do so explicitly in
  205. your program if you want to call FileHandle methods.  This is
  206. done to avoid the overhead of initializing the FileHandle package
  207. in programs which intend to use the handle returned by C<vmsopen>
  208. as a normal Perl file handle only.  When the scalar containing
  209. a VMS::Stdio file handle is overwritten, C<undef>d, or goes
  210. out of scope, the associated file is closed automatically.
  211.  
  212. =item vmssysopen
  213.  
  214. This function bears the same relationship to the CORE function
  215. C<sysopen> as C<vmsopen> does to C<open>.  Its first three arguments
  216. are the name, access flags, and permissions for the file.  Like
  217. C<vmsopen>, it takes up to 8 additional string arguments which
  218. specify file characteristics.  Its return value is identical to
  219. that of C<vmsopen>.
  220.  
  221. The symbolic constants for the mode argument are exported by
  222. VMS::Stdio by default, and are also exported by the Fcntl package.
  223.  
  224. =item waitfh
  225.  
  226. This function causes Perl to wait for the completion of an I/O
  227. operation on the file handle specified as its argument.  It is
  228. used with handles opened for asynchronous I/O, and performs its
  229. task by calling the CRTL routine fwait().
  230.  
  231. =head1 REVISION
  232.  
  233. This document was last revised on 28-Jan-1996, for Perl 5.002.
  234.  
  235. =cut
  236.